docs(readme): document run-capsule shareable run videos#116
Conversation
A run's report.json already carries per-turn screenshot + action + reasoning, so it renders directly into a screen/replay video via run-capsule with no extra capture step. Documents the one-liner under Session Viewer, the screenshot (vision-on) requirement, and the dependency on the suite-aware adapter (tangle-network/run-capsule#4).
tangletools
left a comment
tangletools
left a comment
There was a problem hiding this comment.
✅ Auto-approved PR — c2192d57
Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.
tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-21T14:34:55Z
tangletools
left a comment
tangletools
left a comment
There was a problem hiding this comment.
🟢 Value Audit — sound
| Verdict | sound |
| Concerns | 0 (none) |
| Heuristic | 0.0s |
| Duplication | 0.0s |
| Interrogation | 149.4s (2 bridge agents) |
| Total | 149.4s |
💰 Value — sound
Adds README docs showing how to render a bad run's report.json into captioned shareable MP4s via the external run-capsule CLI; accurate, fits the existing Session Viewer section, and leverages the suite-shaped report schema without bad-side code changes.
- What it does: Appends a 'Shareable run videos' subsection to the README's Session Viewer section (README.md:510) documenting the one-liner
npx run-capsule --playwright agent-results/report.json --no-upload, which turns a completed run's per-turn screenshots, actions, and reasoning intoscreen.mp4andreplay.mp4. - Goals it achieves: Makes users aware that bad's existing report.json trace can be reused (no extra capture step) to produce reasoning-captioned demo/replay videos for sharing, and clarifies the prerequisites: vision-on screenshots and a suite-aware run-capsule adapter.
- Assessment: Good. The docs are accurate — report.json carries TestSuiteResult with per-test screenshots (src/types/test-runner.ts:108) and AgentResult.turns containing action/reasoning per turn (src/types/turn.ts:8, src/types/result.ts:7). The section fits naturally under the existing Session Viewer heading and correctly distinguishes run-capsule's captioned MP4 output from the native
--show-cursorrecordin - Better / existing approach: none for the video-generation goal. The codebase has native
bad sharefor web share links (src/cli-share.ts:2) and--show-cursorfor raw browser recordings, but neither produces a captioned MP4 from report.json; an external tool is the right lightweight approach. Note the README's CLI Reference (README.md:298) already omitsbad shareandbad preview, a pre-existing docs gap unrelated to th - Model: opencode/kimi-for-coding/k2p7
- Bridge attempts: 1
🎯 Usefulness — sound
Docs-only README subsection accurately documents an already-existing capability (report.json's per-turn screenshot+action+reasoning trace) and points at a complementary external video renderer without competing with in-repo tooling.
- Integration: N/A in the code sense — this is a README-only change with no new surface in the repo. The capability it documents already exists: report.json is written as a suite artifact (src/test-runner.ts:626), is suite-shaped TestSuiteResult (src/types/test-runner.ts:126), and the default sink path in the docs (agent-results/report.json) matches src/config.ts:203 and src/cli/commands/run.ts:190. Reachability
- Fit with existing patterns: Fits the grain. The new subsection lives directly under the existing 'Session Viewer' /
bad viewblock (README:507-509) and is explicitly framed as complementary —bad viewfor interactive drill-down,--show-cursorfor an in-run recording.webm, and run-capsule for a captioned shareable video. No competing in-repo video renderer exists (grep for run-capsule returns only the new README lines). - Real-world viability: Docs accuracy holds under the conditions the README itself states. Verified: screenshots are captured per-turn only when vision is on, which defaults ON (src/config.ts:182; src/cli-ui.ts:470-471), so the 'screen capsule shows real frames only when the run captured screenshots' caveat is correct. The suite-shape caveat is also real and honestly flagged: the doc explicitly notes older run-capsule ve
- Model: opencode/zai-coding-plan/glm-5.2
- Bridge attempts: 1
No concerns — sound change, no better or existing approach found. ✅
What this audit checks
It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.
| Pass | What it asks |
|---|---|
| Heuristic | Vague title? Whitespace-only or cruft-bearing diff? (content signals only) |
| Duplication | Do added function/class names already exist elsewhere in the repo? |
| Value Audit | What does it do? What goal does it achieve? Is it good? Better architecture or already-exists? |
| Usefulness Audit | Does it integrate and fit? Will it hold up in real use and actually get used? |
Findings are concerns, not blocks — the human reviewer decides what to do with them.
✅ No Blockers —
|
| deepseek | glm | aggregate | |
|---|---|---|---|
| Readiness | 92 | 92 | 92 |
| Confidence | 65 | 65 | 65 |
| Correctness | 92 | 92 | 92 |
| Security | 92 | 92 | 92 |
| Testing | 92 | 92 | 92 |
| Architecture | 92 | 92 | 92 |
Full multi-shot audit completed 1/1 planned shots over 1 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 1 changed files. Global verifier still owns final merge decision.
🟡 LOW Documents feature backed by unmerged external PR — README.md
Line 520: 'Needs a run-capsule whose Playwright adapter understands this driver's suite-shaped report.json' — the linked PR (tangle-network/run-capsule#4) appears unmerged. Users installing a released run-capsule will get an empty capsule for suite-shaped reports. The caveat is present but easy to miss; consider adding 'until run-capsule#4 merges' for clarity, or waiting to merge this section until the dependency lands.
🟡 LOW Wrong report.json path in run-capsule command example — README.md
README.md:515 shows
npx run-capsule --playwright agent-results/report.json --no-upload, but report.json is written at{baseDir}/suite/report.json, not{baseDir}/report.json. Evidence chain: src/test-runner.ts:625 writes report.json withtestId: 'suite'; src/artifacts/filesystem-sink.ts:75 writes topath.join(this.baseDir, artifact.testId); src/cli/commands/run.ts:190 sets default baseDir to./agent-results. So the real path isagent-results/suite/report.json. Impact: anyone copy-pasting the headline command of this new section gets a file-not-found error on first try. Fix: changeagent-results/report.jsontoagent-results/suite/report.jsonon line 515.
tangletools · 2026-06-21T14:46:52Z · trace
2 participants
Documents how a
badrun becomes a shareable, reasoning-captioned video.A run's
report.jsonis already a complete trace — per-turn screenshot, action, and reasoning — so it renders directly intoscreen.mp4/replay.mp4viarun-capsule, no extra capture step and nobad-side code change. The new "Shareable run videos" subsection (under Session Viewer) gives the one-liner, the screenshot/vision-on requirement, and the dependency on the suite-aware adapter (tangle-network/run-capsule#4).Verified end-to-end against real reports: a 24-turn Variant run renders real product frames each captioned with the agent's 💭 reasoning + action + URL.
Docs-only; no changeset.